nav view/Reviews/2009-10-05 Doc Review

Reviewer:

Instructions for doing a doc review

See DocReviewProcess for more instructions

1. Does the documentation define the Users of your Package, i.e. for the expected usages of your Stack, which APIs will users engage with?
   • JL: No. It comes close in discussion of what nav_view can do. Also unclear how it relates to rviz.
   • GJ: I think it would worth mentioning that nav_view needs to be run in the context of an underlying stack for 2D navigation - later in the doc move_base is mentioned. I also think that it could be clarified that rviz implements a superset of the functionality, but if the functionality of nav_view is sufficient for an application it should generally be used due to simplicity and low resource usage.
2. Are all of these APIs documented?
   • JL: GUI Controls are explained
   • JL: ROS API is mostly clear. Is "/global_frame_id" actually supposed to be a root-level parameter?
   • GJ: Looks fine.
3. Do relevant usages have associated tutorials? (you can ignore this if a Stack-level tutorial covers the relevant usage), and are the indexed in the right places?
   • JL: No package tutorials. Main page is a "micro-tutorial" of sorts, but missing information on running the rest of the system. I could not find a stack-level tutorial that was appropriate. I would like to see something like a tutorial that involved running stage and the nav stack.
   • GJ: As nav_view represents the primary interface to the nav stack, I think that a tutorial would be very useful. Something titled "Using nav_view and stage for simulating 2D navigation". The functionality of the app would be better explained in that context. I can envision people getting very confused when they start nav_view and not very much happens because they aren't running the rest of the nav_stack. Most of the data and the functionality are only generated within the context of the stack.
4. If there are hardware dependencies of the Package, are these documented?
   • N/A
5. Is it clear to an outside user what the roadmap is for the Package?
   • No, but doesnt seem applicable.
6. Is it clear to an outside user what the stability is for the Package?
   • No, but stability seems poorly defined.
7. Are concepts introduced by the Package well illustrated?
   • There are figures for all the commands. A little more text would be helpful such as. "Using the 'Set Pose' tool, click the location in the map where the robot is located, and then drag in the direction of orientation"
8. Is the research related to the Package referenced properly? i.e. can users easily get to relevant papers?
   • N/A
9. Are any mathematical formulas in the Package not covered by papers properly documented?
   • N/A

For each launch file in a Package

1. Is it clear how to run that launch file?
   • N/A
2. Does the launch file start up with no errors when run correctly?
   • N/A
3. Do the Nodes in that launch file correctly use ROS_ERROR/ROS_WARN/ROS_INFO logging levels?
   • N/A

Concerns / issues

• Jeremy: See details above. Would like to see:
  • More clarity about relation to rviz.
    • [Josh] It has no real relation to rviz... what do you want to see here?

  • I'm curious about /global_frame_id being in root namespace

    • [Josh] So am I, not sure when that got added, or who added it.
  • A link to a tutorial that involves running the nav stack in a simulator and using nav_view to set the robots location and and then a goal to move it somewhere. Hopefully the tutorial already exists and I just couldn't find it.
    • NOTE: If it doesn't exit, I'm ok with passing doc-review without this, so long as creating the tutorial is ticketed.
    • [Josh] This doesn't exist, but I don't think it belongs in the nav_view docs
  • A little more specific text for the diagrams as they relate to the commands.
    • [Josh] Done
• Gil: On reflection, I think it's fine to leave this doc as it is as long as there's a note added to the top to the effect that nav_view is meant to run in concert with a navigation stack consisting of a navigator like move_base and a laser-based localization node such as amcl, and that if the nav stack isn't running nav_view isn't going to do very much. I also think a link to a simple tutorial exercising nav stack functionality would be very useful, but that's beyond the scope of this doc review.

Conclusion